SST ShlWAPI PathCreateFromUrl Function

	(SST) ShlWAPI.pas Version 1.08

Developer Reference

(SST)ShlWAPI PathCreateFromUrl Function
Converts the specified Uniform Resource Locator (URL) path string into a path string in DOS/Windows format.

Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).

Syntax
	function PathCreateFromUrl(pszUrl : LPCSTR; pszPath : LPSTR; pcchPath : LPDWORD; dwFlags : DWORD) : HRESULT;
	function PathCreateFromUrlA(pszUrl : LPCSTR; pszPath : LPSTR; pcchPath : LPDWORD; dwFlags : DWORD) : HRESULT; function PathCreateFromUrlW(pszUrl : LPCWSTR; pszPath : LPWSTR; pcchPath : LPDWORD; dwFlags : DWORD) : HRESULT;

Parameters
pszUrl [in]	Pointer to the zero terminated, URL path string to convert. This string may not exceed INTERNET_MAX_URL_LENGTH (= 2055 or 2083 ^*1) characters (ANSI or Unicode) in length.
pszPath [out]	Pointer to the buffer that is to receive the converted, zero-terminated, output string.
pcchPath [in/out]	The address of, or pointer to, an unsigned, 32-bit integer variable. Prior to the call, the referenced variable should be set to the size (in number of characters, including the terminating null character) of the buffer for the converted string, by the caller. The function then sets this variable to the number of characters (not including the terminating null character) written to the buffer, when it returns.
dwFlags [in]	Reserved, should be set to zero (0)

Return Values
If the function was able to succcessfully convert the specified URL path and write the resulting string to the provided buffer it returns S_OK (= 0). If the function fails, it returns a COM eorror code.

Remarks
The function does not appear to support protocols other than the "file" protocol. That is, URLs that begin with http or ftp, for example, even if the localhost (127.0.0.1) is specified as the (root) server/location, are not treanslated into a DOS/Windows path.
(*1) Even though string lengths, that come close to either value, are unlikely to be encountered in practice, it should be noted, that the INTERNET_MAX_URL_LENGTH constant is 2055 in the Delphi 5 SDK and 2083, as declared in WinInet.h of MS SDK Version 6.1. Furthermore, the C/C++ "sizeof" operator of the Microsoft SDK adds one (1), for the terminating null-character to the constant, resulting in a value of 2084 when assigned to a variable.

Remarks

The function does not appear to support protocols other than the "file" protocol. That is, URLs that begin with http or ftp, for example, even if the localhost (127.0.0.1) is specified as the (root) server/location, are not treanslated into a DOS/Windows path.

(*1) Even though string lengths, that come close to either value, are unlikely to be encountered in practice, it should be noted, that the INTERNET_MAX_URL_LENGTH constant is 2055 in the Delphi 5 SDK and 2083, as declared in WinInet.h of MS SDK Version 6.1. Furthermore, the C/C++ "sizeof" operator of the Microsoft SDK adds one (1), for the terminating null-character to the constant, resulting in a value of 2084 when assigned to a variable.

Example
PROCEDURE TForm4.TestShlWAPIPathCreateFromUrl(Sender : TObject); VAR urltoconvert : STRING; VAR pathstrbuf : ARRAY[0.. MAX_PATH] OF CHAR; VAR pathstrlen : DWORD; VAR apiretval : HRESULT; VAR newinfoline : STRING; BEGIN urltoconvert := ''; FillChar(pathstrbuf, Length(pathstrbuf), #0); pathstrlen := 0; apiretval := 0; //= S_OK newinfoline := ''; //The following lines return the DOS path part urltoconvert := 'file:///S:/Projects/SST/SSTWebsite/Develop2016/en/contact/Email.htm'; pathstrlen := Length(pathstrbuf) - 1; newinfoline := 'PathCreateFromUrl called with ' + urltoconvert; Memo1.Lines.Add(newinfoline); apiretval := PathCreateFromUrl(PChar(urltoconvert), @pathstrbuf[0], @pathstrlen, 0); IF apiretval = S_OK THEN newinfoline := pathstrbuf ELSE newinfoline := 'returned error code : ' + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); //The following lines fail urltoconvert := 'http://127.0.0.1/Develop2016/en/products/development%20libraries/delphi/shlwapi/support/DevRef.htm'; pathstrlen := Length(pathstrbuf) - 1; newinfoline := 'PathCreateFromUrl called with ' + urltoconvert; Memo1.Lines.Add(newinfoline); apiretval := PathCreateFromUrl(PChar(urltoconvert), @pathstrbuf[0], @pathstrlen, 0); IF apiretval = S_OK THEN newinfoline := pathstrbuf ELSE newinfoline := 'returned error code : ' + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); Memo1.Lines.Add(''); END;
The above example produces the following output:
PathCreateFromUrl called with file:///S:/Projects/SST/SSTWebsite/Develop2016/en/contact/Email.htm S:\Projects\SST\SSTWebsite\Develop2016\en\contact\Email.htm PathCreateFromUrl called with http://127.0.0.1/Develop2016/en/products/development%20libraries/delphi/shlwapi/support/DevRef.htm returned error code : -2147024809 (0x80070057)

Requirements
Unit:	Declared and imported in (SST)ShlWAPI.pas
Library:	(SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode:	Implemented as ANSI (PathCreateFromUrl and PathCreateFromUrlA) and Unicode (PathCreateFromUrlW) functions.
Min. ShlWAPI.dll version according to MS SDK doc.:	5.0
Min. ShlWAPI.dll version based on SST research:	5.0
Min. OS version(s) according to Microsoft SDK doc.:	Windows 2000, Windows NT 4.0 with Internet Explorer 5, Windows 98, Windows 95 with Internet Explorer 5
Min. OS version(s) according to SST research.:	Windows NT 4.0 with IE 5, Windows 98, Windows 95 with IE 5, Windows 2000 and later

See Also


Windows APIs: PathCreateFromUrl, PathCreateFromUrlAlloc.